home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / ada / gnat1792.zip / gnat179b / gnat-int < prev    next >
Text File  |  1994-06-01  |  47KB  |  1,048 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                              GNAT DOCUMENTS                              --
  4. --                                I N T R O                                 --
  5. --                                                                          --
  6. --                                                                          --
  7. --                                                                          -- 
  8. --                                                                          --
  9. --           Copyright (c) 1992,1993,1994 NYU, All Rights Reserved          --
  10. --                                                                          --
  11. -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12. -- terms  of the GNU  General  Public  License  as  published  by the  Free --
  13. -- Software  Foundation;  either version 2,  or (at your option)  any later --
  14. -- version.  GNAT is distributed  in the hope  that it will be useful,  but --
  15. -- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANT- --
  16. -- ABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public --
  17. -- License  for  more details.  You should have received  a copy of the GNU --
  18. -- General Public License along with GNAT;  see file COPYING. If not, write --
  19. -- to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. --
  20. --                                                                          --
  21. ------------------------------------------------------------------------------
  22.  
  23. Contents.
  24. ---------
  25.    Running GNAT.
  26.    A small example.
  27.    Gnatbl.
  28.    Using the binder.
  29.    Using gcc to compile.
  30.    Using gcc for syntax checking.
  31.    Using gcc for semantics checking.
  32.    Search Paths and the Run Time Library (RTL).
  33.    Options.  
  34.    Constraint Checking and Pragma Suppress
  35.    Order of Compilation Issues.
  36.    File Name Rules.
  37.    Compiling Files With Several Compilation Units.
  38.    Cross Reference Tool.
  39.    Implementation of Intrinsic Functions.
  40.    Getting Internal Debugging Information.
  41.    When GNAT crashes.
  42.    Using gdb.
  43.    Features supported/unsupported.
  44.    Files.
  45.    Copyright considerations.
  46.    How to get in touch with us.
  47.    Schedule.
  48.    A short gnat paper.
  49.    The GNAT development team.
  50. ------------------------------------------------------------------------------ 
  51.  
  52. Running GNAT.
  53. -------------
  54. Three steps are needed to create an executable file from an Ada source file:
  55. it must first be compiled, it then must go through the gnat binder, and then
  56. all appropriate object files it needs are then linked together to produce an
  57. executable.  A tool has been provided to combine the last 2 steps into one
  58. command.
  59.  
  60. A small example.
  61. ----------------
  62.  
  63. The file hello.adb contains the source of our modest version of the
  64. "Hello World" program.  Other components of this program are contained
  65. in the GNAT Runtime Library (RTL).  You needn't mention the files
  66. containing these other components but you can find the sources (io.ads,
  67. io.adb, and a-cio.c) in the RTL source directory (described below).
  68.  
  69. The file hello.adb can be found in the current distribution in the examples
  70. directory.  Here are the commands for building and running it (Since this
  71. documentation is for systems running Unix and also for those running
  72. IBM OS/2 2.x, in places where the instructions differ a prefix "Unix:" or
  73. "OS/2:" indicates what is relevant for each system):
  74.  
  75.             gcc -c hello.adb
  76.       Unix: gnatbl -o hello hello.ali
  77.       OS/2: gnatbl -o hello.exe hello.ali
  78.  
  79. create the executable called "hello" or "hello.exe" in your current directory.
  80. Typing
  81.  
  82.       hello
  83.  
  84. will allow you to verify that the system is alive and willing to enter into 
  85. a primitive dialogue.
  86.  
  87. The gcc switch -c indicates that we only want to compile, not link. The gnatbl
  88. step produces the executable by means of calling the GNAT binder, compiling
  89. its output, and calling gcc with the needed object files and libraries to
  90. link the executable.  The -o switch is passed to the linker to name the
  91. resulting executable file.
  92.  
  93. As the example suggests, the gcc command recognizes the extension .adb as
  94. an indication of an Ada source file and calls the appropriate programs
  95. to generate an object file (hello.o or hello.obj) and an Ada Library
  96. Information (ALI) file (hello.ali) containing dependency information used
  97. by the binder to verify consistency and determine order of elaboration.
  98. The "ali" extension is recognized by gnatbl as the ALI file of the main
  99. procedure or function, and gnatbl uses it to create a file called the
  100. bind file, and to gather all the needed object files for linking.
  101.  
  102.  
  103. Gnatbl
  104. -----
  105. The program gnatbl is being provided on a temporary basis to simplify
  106. binding and linking using the RTL in the most simple situations.  It will
  107. be replaced later by a more complete utility to build a complete Ada
  108. system.  Gnatbl calls gnatbind which creates a C file (b_hello.c in our
  109. simple example) containing calls to all of the elaboration routines.
  110. Gnatbind is described more fully below.  The typical use of GNAT (currently
  111. -- in the presence of gnatbl) to construct a program consisting of a mix
  112. of Ada and C sources is to compile all of the sources using "gcc -c" to
  113. generate object (.o or .obj) files.  In the case of Ada sources, ALI files
  114. with the extension .ali are also produced.  Then gnatbl is used to construct
  115. the executable.  All arguments to gnatbl are simply passed through to gcc
  116. to link the objects together, with the exception of a file name with the
  117. .ali extension.  Such an argument is presumed to be the ALI file of the
  118. main procedure of the program.  When gnatbl sees a .ali file it calls gnatbind
  119. to create the bind file, compiles the bind file, extracts a list of needed
  120. object files from the bind file, and replaces the .ali argument with the
  121. a list of object files (the result of compiling the bind file and the list
  122. extracted from the bind file) in the gcc command it makes.  As a quick
  123. illustration consider a program comprising main.adb, foo.adb and bar.c.
  124. After compiling these sources into object files, the command (under Unix)
  125.  
  126. gnatbl -o main main.ali bar.o
  127.  
  128. would cause gnatbl to:
  129.   call "gnatbind main.ali", generating b_main.c
  130.   call "gcc -c b_main.c"
  131.   call "gcc -o b_main.o main.o foo.o bar.o (+ gnat library args)"
  132.  
  133. In the last step, the "main.ali" argument has been replaced by all of the
  134. object files needed by main (the binder file, main itself, and foo -- upon
  135. which main depends). All other gnatbl arguments are passed through unchanged
  136. to gcc.  Finally a -l and a -L argument are added to the end of the gcc call
  137. to point it to the gnatlib library.  (Under OS/2, the command line and
  138. behavior of gnatbl is similar.)
  139.  
  140. A current limitation of the very simplistic gnatbl is that the main program
  141. must be Ada and that it depends on all of the necessary library units.  In
  142. other words, there can be only one .ali file listed and it must be the
  143. main program.  This particularly restricts gnatbl's use when a routine written
  144. in another language calls an Ada subprogram which is not also called from
  145. Ada.
  146.  
  147.  
  148. Using the Binder.
  149. -----------------
  150.  
  151. In the "Hello World" example, if gnatbl were not used, the second step
  152. would have been to call the binder directly with the command:
  153.  
  154.        gnatbind hello.ali
  155.  
  156. This command generates a file named b_hello.c which needs to be compiled and
  157. linked together with hello.o (or hello.obj).  The file b_hello.c contains
  158. a program which contains calls to all of the elaboration routines of all
  159. of the units required by the subprogram whose ALI file is given on the command
  160. line.  Then it calls the Ada subprogram itself.  By default, this C function
  161. is called "main".  (For other options, see the section on options below.)
  162. The program gnatbind works by recursively processing the ALI files of all
  163. of the units that are needed.  These ALI files are found using the search
  164. path mechanism described below.